────────────────────────────────────────
SAC → CSV CONVERSION GUIDE
(using sac_to_csv.py)
────────────────────────────────────────

PURPOSE
Convert seismic SAC waveform files into simple:

time, amplitude

CSV format for UNNS structural pipeline.

────────────────────────────────────────
1. REQUIREMENTS
────────────────────────────────────────

Python installed ✔

Install dependencies (once):

    pip install obspy pandas

If warning about PATH appears → ignore (not critical)

────────────────────────────────────────
2. FILE STRUCTURE
────────────────────────────────────────

Folder should contain:

    sac_to_csv.py
    *.SAC files

Example:

    IU.MIDW.00.BHZ.D.2026.125.211842.SAC
    IU.RAO.00.BHZ.D.2026.125.211443.SAC
    IU.HNR.00.BHZ.D.2026.125.211627.SAC

────────────────────────────────────────
3. BASIC USAGE (SINGLE FILE)
────────────────────────────────────────

Run in PowerShell:

    python sac_to_csv.py IU.MIDW.00.BHZ.D.2026.125.211842.SAC

Output:

    IU.MIDW.00.BHZ.D.2026.125.211842.csv

────────────────────────────────────────
4. BATCH CONVERSION (RECOMMENDED)
────────────────────────────────────────

Convert ALL SAC files in folder:

PowerShell:

    for %f in (*.SAC) do python sac_to_csv.py "%f"

(If inside script or .bat file, use %%f instead)

────────────────────────────────────────
5. OUTPUT FORMAT
────────────────────────────────────────

Each CSV contains:

    time,amplitude

Example:

    0.0000, -0.00012
    0.0250,  0.00045
    0.0500,  0.00187
    ...

time:
    seconds from trace start

amplitude:
    raw ground motion (counts)

────────────────────────────────────────
6. QUICK VALIDATION (IMPORTANT)
────────────────────────────────────────

Open CSV and check:

✔ time increases monotonically  
✔ amplitude not constant  
✔ visible spike + decay structure  

Reject if:
✘ flat signal  
✘ only noise  
✘ broken values  

────────────────────────────────────────
7. COMMON ERRORS
────────────────────────────────────────

ERROR: "File not found"

→ Check filename spelling
→ Use quotes if needed

ERROR: nothing happens

→ Wrong folder
→ Not running inside SAC file directory

ERROR: obsPy import fails

→ Run:

    pip install obspy

────────────────────────────────────────
8. NEXT STEP (MANDATORY)
────────────────────────────────────────

DO NOT feed raw amplitude into UNNS.

Next pipeline stage:

    CSV → Δamplitude → structural ladder

────────────────────────────────────────
END
────────────────────────────────────────